.TH stoker_py 8 "17 September 2008" "version 0.91" "Stoker Manual"
.SH NAME
stoker (py) \- extend Stoker using a Python script
.SH SYNOPSIS
.B stoker
[OPTIONS] <machine(s)> py <python_file> [arguments]

.B stoker
<\-a | \-\-all> [OPTIONS] py <python_file> [arguments]
.SH DESCRIPTION
The stoker(8) py command loads a Python file an executes a special function
(stoker_hook) in that file, passing it the configuration from stoker.conf(5),
any command arguments, and the target on which the Python file should be
executed.
This process is repeated once for each target machine.
Global OPTIONS are documented in the man page for stoker(8).
.SH REQUIREMENTS
The Python module to be loaded MUST contain a function named "stoker_hook"
that takes EXACTLY ONE argument.
Stoker will invoke stoker_hook with an argument consisting of a Python
object representing a data structure with the following fields:
.TP
.B stoker_config
The scf2.ConfigHandler object created from stoker.conf(5).

.TP
.B args
The array of arguments passed by the user to the py command.

.TP
.B target
The target machine on which the command is to be executed, resolved either
to hostname or IP address as specified in stoker.conf(5).

.TP
.B stdinput
A string containing any standard input that has been redirected to the module
for the current target.
If no standard input is available, this field will contain an empty string.
.PP
The stoker_hook command MUST return a tuple: (code, out, err), which
correspond to the return code (0-255), standard output string, and standard
error string, respectively.
.SH CAUTION
Python files invoked by the py command can change the Stoker global
configuration for the running instance.
However, any such changes will NOT be persistent and will affect only
additional targets to the py command.
.SH EXIT STATUS
Stoker will return the code specified by the external Python file, or a
non-zero code if the Python file could not be loaded or causes an error.
.SH SEE ALSO
stoker(8), stoker.conf(5)
.SH AUTHOR
Mike Murphy (mamurph@cs.clemson.edu)
.SH DISCLAIMER
This material is based upon work supported under a National Science
Foundation Graduate Research Fellowship.
Any opinions, findings, conclusions or recommendations expressed in this
publication are those of the author(s) and do not necessarily reflect the
views of the National Science Foundation.
